
<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta charset="utf-8" />
    <title>9.4. Key identifiers &#8212; PSA Crypto API 1.0.1 documentation</title>
    <link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
    <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
    <script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
    <script type="text/javascript" src="../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../_static/doctools.js"></script>
    <script type="text/javascript" src="../../_static/language_data.js"></script>
    <link rel="author" title="About these documents" href="../../about.html" />
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="next" title="9.5. Key policies" href="policy.html" />
    <link rel="prev" title="9.3. Key lifetimes" href="lifetimes.html" />
   
  <link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
  
  
  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />

  </head><body>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          

          <div class="body" role="main">
            
  <div class="section" id="key-identifiers">
<span id="id1"></span><h1>9.4. Key identifiers</h1>
<p>Key identifiers are integral values that act as permanent names for persistent keys, or as transient references to volatile keys. Key identifiers use the <a class="reference internal" href="#c.psa_key_id_t" title="psa_key_id_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_key_id_t</span></code></a> type, and the range of identifier values is divided as follows:</p>
<dl class="simple">
<dt><a class="reference internal" href="#c.PSA_KEY_ID_NULL" title="PSA_KEY_ID_NULL"><code class="docutils literal notranslate"><span class="pre">PSA_KEY_ID_NULL</span></code></a><code class="docutils literal notranslate"> <span class="pre">=</span> <span class="pre">0</span></code></dt><dd><p>Reserved as an invalid key identifier.</p>
</dd>
<dt><a class="reference internal" href="#c.PSA_KEY_ID_USER_MIN" title="PSA_KEY_ID_USER_MIN"><code class="docutils literal notranslate"><span class="pre">PSA_KEY_ID_USER_MIN</span></code></a><code class="docutils literal notranslate"> <span class="pre">-</span> </code><a class="reference internal" href="#c.PSA_KEY_ID_USER_MAX" title="PSA_KEY_ID_USER_MAX"><code class="docutils literal notranslate"><span class="pre">PSA_KEY_ID_USER_MAX</span></code></a></dt><dd><p>Applications can freely choose persistent key identifiers in this range.</p>
</dd>
<dt><a class="reference internal" href="#c.PSA_KEY_ID_VENDOR_MIN" title="PSA_KEY_ID_VENDOR_MIN"><code class="docutils literal notranslate"><span class="pre">PSA_KEY_ID_VENDOR_MIN</span></code></a><code class="docutils literal notranslate"> <span class="pre">-</span> </code><a class="reference internal" href="#c.PSA_KEY_ID_VENDOR_MAX" title="PSA_KEY_ID_VENDOR_MAX"><code class="docutils literal notranslate"><span class="pre">PSA_KEY_ID_VENDOR_MAX</span></code></a></dt><dd><p>Implementations can define additional persistent key identifiers in this range, and must allocate any volatile key identifiers from this range.</p>
</dd>
</dl>
<p>Key identifiers outside these ranges are reserved for future use.</p>
<p>Key identifiers are output from a successful call to one of the key creation functions. For persistent keys, this is the same identifier as the one specified in the key attributes used to create the key. The key identifier remains valid until it is invalidated by passing it to <a class="reference internal" href="management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_destroy_key()</span></code></a>. A volatile key identifier must not be used after it has been invalidated.</p>
<p>If an invalid key identifier is provided as a parameter in any function, the function will return <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a>; except for the special case of calling <a class="reference internal" href="management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="docutils literal notranslate"><span class="pre">psa_destroy_key</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><a class="reference internal" href="#c.PSA_KEY_ID_NULL" title="PSA_KEY_ID_NULL"><code class="docutils literal notranslate"><span class="pre">PSA_KEY_ID_NULL</span></code></a><code class="docutils literal notranslate"><span class="pre">)</span></code>, which has no effect and always returns <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a>.</p>
<p>Valid key identifiers must have distinct values within the same application. If the implementation provides <a class="reference internal" href="../../overview/goals.html#isolation"><span class="std std-ref">caller isolation</span></a>, then key identifiers are local to each application. That is, the same key identifier in two applications corresponds to two different keys.</p>
<div class="section" id="key-identifier-type">
<h2>9.4.1. Key identifier type</h2>
<div class="section" id="psa_key_id_t">
<span id="c.psa_key_id_t"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_key_id_t</span></code> (type)</h3>
<p>Key identifier.</p>
<pre class="literal-block">typedef uint32_t <a class="reference internal" href="#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a>;</pre>
<p>A key identifier can be a permanent name for a persistent key, or a transient reference to volatile key. See <a class="reference internal" href="#key-identifiers"><span class="secref">Key identifiers</span></a>.</p>
</div>
<div class="section" id="PSA_KEY_ID_NULL">
<span id="c.PSA_KEY_ID_NULL"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_KEY_ID_NULL</span></code> (macro)</h3>
<p>The null key identifier.</p>
<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_KEY_ID_NULL" title="PSA_KEY_ID_NULL">PSA_KEY_ID_NULL</a> ((<a class="reference internal" href="#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a>)0)</pre>
<p>The null key identifier is always invalid, except when used without in a call to <a class="reference internal" href="management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_destroy_key()</span></code></a> which will return <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a>.</p>
</div>
<div class="section" id="PSA_KEY_ID_USER_MIN">
<span id="c.PSA_KEY_ID_USER_MIN"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_KEY_ID_USER_MIN</span></code> (macro)</h3>
<p>The minimum value for a key identifier chosen by the application.</p>
<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_KEY_ID_USER_MIN" title="PSA_KEY_ID_USER_MIN">PSA_KEY_ID_USER_MIN</a> ((<a class="reference internal" href="#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a>)0x00000001)</pre>
</div>
<div class="section" id="PSA_KEY_ID_USER_MAX">
<span id="c.PSA_KEY_ID_USER_MAX"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_KEY_ID_USER_MAX</span></code> (macro)</h3>
<p>The maximum value for a key identifier chosen by the application.</p>
<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_KEY_ID_USER_MAX" title="PSA_KEY_ID_USER_MAX">PSA_KEY_ID_USER_MAX</a> ((<a class="reference internal" href="#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a>)0x3fffffff)</pre>
</div>
<div class="section" id="PSA_KEY_ID_VENDOR_MIN">
<span id="c.PSA_KEY_ID_VENDOR_MIN"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_KEY_ID_VENDOR_MIN</span></code> (macro)</h3>
<p>The minimum value for a key identifier chosen by the implementation.</p>
<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_KEY_ID_VENDOR_MIN" title="PSA_KEY_ID_VENDOR_MIN">PSA_KEY_ID_VENDOR_MIN</a> ((<a class="reference internal" href="#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a>)0x40000000)</pre>
</div>
<div class="section" id="PSA_KEY_ID_VENDOR_MAX">
<span id="c.PSA_KEY_ID_VENDOR_MAX"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_KEY_ID_VENDOR_MAX</span></code> (macro)</h3>
<p>The maximum value for a key identifier chosen by the implementation.</p>
<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_KEY_ID_VENDOR_MAX" title="PSA_KEY_ID_VENDOR_MAX">PSA_KEY_ID_VENDOR_MAX</a> ((<a class="reference internal" href="#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a>)0x7fffffff)</pre>
</div>
</div>
<div class="section" id="attribute-accessors">
<h2>9.4.2. Attribute accessors</h2>
<div class="section" id="psa_set_key_id">
<span id="c.psa_set_key_id"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_set_key_id</span></code> (function)</h3>
<p>Declare a key as persistent and set its key identifier.</p>
<pre class="literal-block">void <a class="reference internal" href="#c.psa_set_key_id" title="psa_set_key_id">psa_set_key_id</a>(<a class="reference internal" href="attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> * attributes,
                    <a class="reference internal" href="#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> id);</pre>
<p class="rubric">Parameters</p>
<dl class="simple">
<dt> <code class="docutils literal notranslate"><span class="pre">attributes</span></code></dt><dd><p>The attribute object to write to.</p>
</dd>
<dt> <code class="docutils literal notranslate"><span class="pre">id</span></code></dt><dd><p>The persistent identifier for the key.</p>
</dd>
</dl>
<p class="rubric">Returns: <code class="docutils literal notranslate"><span class="pre">void</span></code></p>
<p class="rubric">Description</p>
<p>The application must choose a value for <code class="docutils literal notranslate"><span class="pre">id</span></code> between <a class="reference internal" href="#c.PSA_KEY_ID_USER_MIN" title="PSA_KEY_ID_USER_MIN"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_ID_USER_MIN</span></code></a> and <a class="reference internal" href="#c.PSA_KEY_ID_USER_MAX" title="PSA_KEY_ID_USER_MAX"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_ID_USER_MAX</span></code></a>.</p>
<p>If the attribute object currently declares the key as volatile, which is the default lifetime of an attribute object, this function sets the lifetime attribute to <a class="reference internal" href="lifetimes.html#c.PSA_KEY_LIFETIME_PERSISTENT" title="PSA_KEY_LIFETIME_PERSISTENT"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_LIFETIME_PERSISTENT</span></code></a>.</p>
<p>This function does not access storage, it merely stores the given value in the attribute object. The persistent key will be written to storage when the attribute object is passed to a key creation function such as <a class="reference internal" href="management.html#c.psa_import_key" title="psa_import_key"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_import_key()</span></code></a>, <a class="reference internal" href="management.html#c.psa_generate_key" title="psa_generate_key"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_generate_key()</span></code></a>, <a class="reference internal" href="../ops/kdf.html#c.psa_key_derivation_output_key" title="psa_key_derivation_output_key"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_key_derivation_output_key()</span></code></a> or <a class="reference internal" href="management.html#c.psa_copy_key" title="psa_copy_key"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_copy_key()</span></code></a>.</p>
<div class="admonition-implementation-note admonition">
<p class="admonition-title">Implementation note</p>
<p>This is a simple accessor function that is not required to validate its inputs. The following approaches can be used to provide an efficient implementation:</p>
<ul class="simple">
<li><p>This function can be declared as <code class="docutils literal notranslate"><span class="pre">static</span></code> or <code class="docutils literal notranslate"><span class="pre">inline</span></code>, instead of using the default external linkage.</p></li>
<li><p>This function can be provided as a function-like macro. In this form, the macro must evaluate each of its arguments exactly once, as if it was a function call.</p></li>
</ul>
</div>
</div>
<div class="section" id="psa_get_key_id">
<span id="c.psa_get_key_id"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_get_key_id</span></code> (function)</h3>
<p>Retrieve the key identifier from key attributes.</p>
<pre class="literal-block"><a class="reference internal" href="#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> <a class="reference internal" href="#c.psa_get_key_id" title="psa_get_key_id">psa_get_key_id</a>(const <a class="reference internal" href="attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> * attributes);</pre>
<p class="rubric">Parameters</p>
<dl class="simple">
<dt> <code class="docutils literal notranslate"><span class="pre">attributes</span></code></dt><dd><p>The key attribute object to query.</p>
</dd>
</dl>
<p class="rubric">Returns: <a class="reference internal" href="#c.psa_key_id_t" title="psa_key_id_t"><code class="docutils literal notranslate"><span class="pre">psa_key_id_t</span></code></a></p>
<p>The persistent identifier stored in the attribute object. This value is unspecified if the attribute object declares the key as volatile.</p>
<p class="rubric">Description</p>
<div class="admonition-implementation-note admonition">
<p class="admonition-title">Implementation note</p>
<p>This is a simple accessor function that is not required to validate its inputs. The following approaches can be used to provide an efficient implementation:</p>
<ul class="simple">
<li><p>This function can be declared as <code class="docutils literal notranslate"><span class="pre">static</span></code> or <code class="docutils literal notranslate"><span class="pre">inline</span></code>, instead of using the default external linkage.</p></li>
<li><p>This function can be provided as a function-like macro. In this form, the macro must evaluate each of its arguments exactly once, as if it was a function call.</p></li>
</ul>
</div>
</div>
</div>
</div>


          </div>
          
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
IHI 0086<br/>
Non-confidential<br/>
Version 1.0.1
<span style="color: red; font-weight: bold;"></span>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../about.html">About this document</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">9. Key management reference</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="attributes.html">9.1. Key attributes</a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html">9.2. Key types</a></li>
<li class="toctree-l2"><a class="reference internal" href="lifetimes.html">9.3. Key lifetimes</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">9.4. Key identifiers</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#key-identifier-type">9.4.1. Key identifier type</a></li>
<li class="toctree-l3"><a class="reference internal" href="#attribute-accessors">9.4.2. Attribute accessors</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="policy.html">9.5. Key policies</a></li>
<li class="toctree-l2"><a class="reference internal" href="management.html">9.6. Key management functions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../ops/index.html">10. Cryptographic operation reference</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
</ul>
<div id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="../../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" />
      <input type="submit" value="Go" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="footer">
      &copy; 2018-2020, Arm Limited or its affiliates. All rights reserved.
      
      |
      Powered by <a href="http://sphinx-doc.org/">Sphinx 2.1.2</a>
      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
      
    </div>

    

    
  </body>
</html>